---
title: CLI 명령
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'
import Badge from '~/components/Badge.astro';


Astro에서 제공하는 명령줄 인터페이스 (CLI)를 사용하여 터미널 창에서 프로젝트를 개발, 빌드, 미리 볼 수 있습니다.

### `astro` 명령

원하는 패키지 관리자로 이 페이지에 설명된 **명령** 중 하나를 실행하고 선택적으로 **플래그**를 실행하여 CLI를 사용하세요. 플래그는 명령의 동작을 사용자 정의합니다.

가장 자주 사용하게 될 명령 중 하나는 `astro dev`입니다. 이 명령은 개발 서버를 시작하고 작업하는 동안 브라우저에서 사이트의 실시간 업데이트 미리보기를 제공합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 개발 서버를 시작합니다.
  npx astro dev
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 개발 서버를 시작합니다.
  pnpm astro dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 개발 서버를 시작합니다.
  yarn astro dev
  ```
  </Fragment>
</PackageManagerTabs>

터미널에 `astro --help`를 입력하면 사용 가능한 모든 명령 목록을 표시할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro --help
  ```
  </Fragment>
</PackageManagerTabs>

터미널에 다음 메시지가 표시됩니다.

```bash
astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate content collection types.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --open  Open the app in the browser on server start.
           --help  Show this help message.
```

:::note
`npm`이 플래그를 `astro` 명령에 전달하려면 플래그 앞에 추가 `--`가 필요합니다.
:::

### `package.json` 스크립트

이러한 명령의 더 짧은 버전에 `package.json`의 스크립트를 사용할 수도 있습니다. 스크립트를 사용하면 `npm run build`와 같이 다른 프로젝트에서 익숙할 수 있는 동일한 명령을 사용할 수 있습니다.

가장 일반적인 `astro` 명령 (`astro dev`, `astro build`, `astro preview`)에 대한 다음 스크립트는 [`create astro` 마법사](/ko/install/auto/#1-설치-마법사-실행하기)를 사용하여 프로젝트를 생성할 때 자동으로 추가됩니다.

[Astro 수동 설치](/ko/install/manual/#2-astro-설치) 지침을 따르면 이러한 스크립트를 직접 추가하라는 메시지가 표시됩니다. 자주 사용하는 명령에 대해 수동으로 이 목록에 더 많은 스크립트를 추가할 수도 있습니다.

```json title="package.json"
{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
```

플래그 없이 이러한 `astro` 명령이나 이를 실행하는 스크립트를 자주 사용하게 됩니다. 명령의 동작을 사용자 정의하려면 명령에 플래그를 추가하세요. 예를 들어, 다른 포트에서 개발 서버를 시작하거나 디버깅을 위해 자세한 로그를 사용하여 사이트를 구축할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  npm run start -- --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  npm run build -- --verbose
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  pnpm start --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  pnpm build --verbose
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  yarn start --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  yarn build --verbose
  ```
  </Fragment>
</PackageManagerTabs>

{/*

ORIGINAL CONTENT That We Can Always revert to if new stuff is too friendly

You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.

Use the CLI by running one of the **commands** documented on this page, optionally followed by any **flags**. Flags customize the behavior of a command. For example, to start the development server on port `8080`, you would combine the `astro dev` command with the `--port` flag: `astro dev --port 8080`.

In most cases you will use the CLI via your package manager:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro dev --port 8080
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro dev --port 8080
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro dev --port 8080
  ```
  </Fragment>
</PackageManagerTabs>

If you started your project using [the `create astro` wizard](/en/install/auto/#1-run-the-setup-wizard), you can also use the scripts in `package.json` for a shorter version of these commands. See the `README.md` in your project for details of which commands are available.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # run the dev server on port 8080 using the `start` script in `package.json`
  npm run start -- --port 8080
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # run the dev server on port 8080 using the `start` script in `package.json`
  pnpm start --port 8080
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # run the dev server on port 8080 using the `start` script in `package.json`
  yarn start --port 8080
  ```
  </Fragment>
</PackageManagerTabs>

*/}

## `astro dev`

Astro의 개발 서버를 실행합니다. 이는 자산을 번들로 묶지 않는 로컬 HTTP 서버입니다. HMR (Hot Module Replacement)을 사용하여 편집기에 변경 사항을 저장할 때 브라우저를 업데이트합니다.

## `astro build`

배포용 사이트를 빌드합니다. 기본적으로 이는 정적 파일을 생성하여 `dist/` 디렉터리에 저장합니다. [SSR이 활성화된 경우](/ko/guides/server-side-rendering/), 사이트를 제공하는 데 필요한 서버 파일이 생성됩니다.

아래에 설명된 [공통 플래그](#공통-플래그)와 결합할 수 있습니다.

## `astro preview`

`astro build`를 실행하여 생성된 정적 디렉터리 (기본적으로 `dist/`)의 콘텐츠를 제공하기 위해 로컬 서버를 시작합니다.

이 명령을 사용하면 [빌드 후](#astro-build) 로컬에서 사이트를 미리 보고 배포하기 전에 빌드 출력에서 ​​오류를 확인할 수 있습니다. 프로덕션 환경에서 실행되도록 설계되지 않았습니다. 프로덕션 호스팅에 대한 도움이 필요하면 [Astro 웹사이트 배포](/ko/guides/deploy/) 안내서를 확인하세요.

Astro 1.5.0부터 `astro preview`는 이를 지원하는 어댑터를 사용하는 경우 SSR 빌드에서도 작동합니다. 현재는 [Node 어댑터](/ko/guides/integrations-guide/node/)에서만 `astro preview`를 지원합니다.

아래에 설명된 [공통 플래그](#공통-플래그)와 결합할 수 있습니다.

## `astro check`

프로젝트에 대해 진단 (예: `.astro` 파일 내 타입 검사)을 실행하고 오류를 콘솔에 보고합니다. 오류가 발견되면 프로세스는 **1** 코드와 함께 종료됩니다.

이 명령은 CI 워크플로에서 사용하기 위한 것입니다.

<h3>플래그</h3>

명령의 동작을 사용자 정의하려면 이러한 플래그를 사용하세요.

#### `--watch`

이 명령은 프로젝트의 변경 사항을 감시하고 오류를 보고합니다.

<ReadMore>[Astro의 타입 검사](/ko/guides/typescript/#타입-검사)에 대해 자세히 알아보세요.</ReadMore>

## `astro sync`

<p><Since v="2.0.0" /></p>

:::tip
`astro dev`, `astro build`, `astro check`를 실행하면 `sync` 명령도 실행됩니다.
:::

모든 Astro 모듈에 대한 TypeScript 타입을 생성합니다. 이는 타입 추론을 위한 [`src/env.d.ts` 파일](/ko/guides/typescript/#설정)을 설정하고 생성된 타입에 의존하는 기능에 대한 모듈을 정의합니다.

- `astro:content` [콘텐츠 컬렉션 API](/ko/guides/content-collections/)를 위한 모듈
- `astro:db` [Astro DB](/ko/guides/astro-db/)를 위한 모듈

## `astro add`

구성에 통합을 추가합니다. [통합 안내서](/ko/guides/integrations-guide/#자동-통합-설정)에서 자세히 알아보세요.

## `astro docs`

터미널에서 직접 Astro 문서 웹사이트를 시작합니다.

## `astro info`

현재 Astro 환경에 대한 유용한 정보를 보고합니다. 이슈를 열 때 정보를 제공하는 데 유용합니다.

```shell
astro info
```

Example output:

```
Astro                    v3.0.12
Node                     v20.5.1
System                   macOS (arm64)
Package Manager          pnpm
Output                   server
Adapter                  @astrojs/vercel/serverless
Integrations             none
```

## `astro preferences`

`astro preferences` 명령으로 사용자 기본 설정을 관리하세요. 프로젝트에 참여하는 모든 사람의 동작을 변경하는 `astro.config.mjs` 파일과 달리 사용자 기본 설정은 개별 Astro 사용자에게만 적용됩니다.

사용자 기본 설정은 기본적으로 현재 프로젝트로 범위가 지정되며 로컬 `.astro/settings.json` 파일에 저장됩니다.

`--global` 플래그를 사용하면 현재 시스템의 모든 Astro 프로젝트에 사용자 기본 설정을 적용할 수도 있습니다. 전역 사용자 기본 설정은 운영 체제별 위치에 저장됩니다.

예를 들어, 특정 Astro 프로젝트에서 devToolbar를 비활성화하려면:

```shell
astro preferences disable devToolbar
```

현재 머신의 모든 Astro 프로젝트에서 devToolbar를 비활성화하려면:

```shell
astro preferences disable --global devToolbar
```

devToolbar는 나중에 다음을 사용하여 활성화할 수 있습니다.

```shell
astro preferences enable devToolbar
```

`reset` 명령은 기본 설정을 기본값으로 재설정합니다.

```shell
astro preferences reset devToolbar
```

`list` 명령은 구성 가능한 모든 사용자 기본 설정의 현재 설정을 출력합니다. 또한 기계가 읽을 수 있는 `--json` 출력을 지원합니다.

```shell
astro preferences list
```

## `astro telemetry`

현재 CLI 사용자에 대한 원격 측정 구성을 설정합니다. 원격 측정은 Astro 팀에 Astro 기능이 가장 자주 사용되는 통찰력을 제공하는 익명 데이터입니다. 자세한 내용은 [Astro의 원격 측정 페이지](https://astro.build/telemetry/)를 참조하세요.

다음 CLI 명령을 사용하여 원격 측정을 비활성화할 수 있습니다.

```shell
astro telemetry disable
```

나중에 다음을 사용하여 원격 측정을 다시 활성화할 수 있습니다.

```shell
astro telemetry enable
```

`reset` 명령은 원격 측정 데이터를 초기화합니다.

```shell
astro telemetry reset
```

:::tip[CI 환경에서 원격 측정을 비활성화하고 싶으십니까?]
CI 스크립트에 `astro telemetry disable` 명령을 추가하거나 `ASTRO_TELEMETRY_DISABLED` 환경 변수를 설정하세요.
:::

## 공통 플래그

### `--root <path>`

프로젝트 루트의 경로를 지정합니다. 지정하지 않으면 현재 작업 디렉터리가 루트로 간주됩니다.

루트는 Astro 구성 파일을 찾는 데 사용됩니다.

```shell
astro --root myRootFolder/myProjectFolder dev
```

### `--config <path>`

프로젝트 루트를 기준으로 구성 파일의 경로를 지정합니다. 기본값은 `astro.config.mjs`입니다. 구성 파일에 다른 이름을 사용하거나 구성 파일이 다른 폴더에 있는 경우 이 방법을 사용하세요.

```shell
astro --config config/astro.config.mjs dev
```

### `--outDir <path>`

<p><Since v="3.3.0" /></p>

프로젝트에 대한 [`outDir`](/ko/reference/configuration-reference/#outdir)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `outDir` 값이 있는 경우 이를 재정의합니다.

### `--site <url>`

프로젝트에 대한 [`site`](/ko/reference/configuration-reference/#site)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `site` 값이 있는 경우 이를 재정의합니다.

### `--base <pathname>`

<p><Since v="1.4.1" /></p>

프로젝트에 대한 [`base`](/ko/reference/configuration-reference/#base)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `base` 값이 있는 경우 이를 재정의합니다.

### `--port <number>`

개발 서버와 미리보기 서버를 실행할 포트를 지정합니다. 기본값은 `4321`입니다.

### `--host [선택적 호스트 주소]`

개발 서버와 미리 보기 서버가 수신 대기해야 하는 네트워크 IP 주소 (예: localhost가 아닌 IP)를 설정합니다. 이는 개발 중 휴대폰과 같은 로컬 장치에서 프로젝트를 테스트하는 데 유용할 수 있습니다.

- `--host` — LAN 및 공용 주소를 포함한 모든 주소에서 수신
- `--host <사용자 정의 주소>` — `<사용자 정의 주소>`에 네트워크 IP 주소 노출

:::caution
프로덕션 환경에서 개발 서버 및 미리보기 서버를 노출하기 위해 `--host` 플래그를 사용하지 마세요. 서버는 사이트를 개발하는 동안에만 로컬 사용을 위해 설계되었습니다.
:::

### `--verbose`

문제를 디버깅할 때 유용한 자세한 로깅을 활성화합니다.

### `--silent`

콘솔 출력 없이 서버를 실행하는 자동 로깅을 활성화합니다.

## Global flags

이 플래그를 사용하여 `astro` CLI에 대한 정보를 얻으세요.

### `--version`

Astro 버전 번호를 출력하고 종료합니다.

### `--open`

서버 시작 시 브라우저에서 앱을 자동으로 엽니다. 열려는 URL을 지정하기 위해 전체 URL 문자열 (예: `--open http://example.com`) 또는 경로 이름 (예: `--open /about`)을 전달할 수 있습니다.

### `--help`

도움말 메시지를 출력하고 종료합니다.

## 고급 API (실험적 기능)

Astro를 실행할 때 더 많은 제어가 필요한 경우 `"astro"` 패키지는 프로그래밍 방식으로 CLI 명령을 실행하기 위해 API를 내보냅니다.

이러한 API는 실험적이며 API 시그니처가 변경될 수 있습니다. 모든 업데이트는 [Astro 변경 로그](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md)에 언급되며 아래 정보는 항상 최신 정보를 표시합니다.

### `AstroInlineConfig`

`AstroInlineConfig` 타입은 아래의 모든 명령 API에서 사용됩니다. 이는 사용자 [Astro 구성](/ko/reference/configuration-reference/) 타입에서 확장됩니다.

```ts
interface AstroInlineConfig extends AstroUserConfig {
	configFile?: string | false;
	mode?: "development" | "production";
	logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}
```

#### `configFile`

<p>

**타입:** `string | false`<br />
**기본값:** `undefined`
</p>

Astro 구성 파일의 사용자 정의 경로입니다.

이 값이 undefined이거나 (기본값) 설정되지 않은 경우 Astro는 `root`를 기준으로 `astro.config.(js,mjs,ts)` 파일을 검색하고 발견되면 구성 파일을 로드합니다.

상대 경로가 설정되면 현재 작업 디렉터리를 기반으로 확인됩니다.

구성 파일 로드를 비활성화하려면 `false`로 설정하세요.

이 객체에 전달된 인라인 구성은 로드된 사용자 구성과 병합될 때 가장 높은 우선순위를 갖습니다.

#### `mode`

<p>

**타입:** `"development" | "production"`<br />
**기본값:** `astro dev`를 실행할 때 `"development"`, `astro build`를 실행할 때 `"production"`
</p>

"development" 또는 "production" 코드를 생성하기 위해 사이트를 빌드할 때 사용되는 모드입니다.

#### `logLevel`

<p>

**타입:** `"debug" | "info" | "warn" | "error" | "silent"`<br />
**기본값:** `"info"`
</p>

Astro가 기록한 메시지를 필터링하는 로깅 수준입니다.

- `"debug"`: 자세한 디버깅 진단을 포함한 모든 것을 기록합니다.
- `"info"`: 정보 메시지, 경고, 오류를 기록합니다.
- `"warn"`: 경고 및 오류를 기록합니다.
- `"error"`: 오류만 기록합니다.
- `"silent"`: 아무것도 기록하지 않습니다.

### `dev()`

**타입:** `(inlineConfig: AstroInlineConfig) => AstroDevServer`

[`astro dev`](#astro-dev)와 유사하게 Astro의 개발 서버를 실행합니다.

```js
import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await devServer.stop();
```

### `build()`

**타입:** `(inlineConfig: AstroInlineConfig) => void`

[`astro build`](#astro-build)와 유사하게 배포용 사이트를 빌드합니다.

```js
import { build } from "astro";

await build({
  root: "./my-project",
});
```

### `preview()`

**타입:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer`

[`astro preview`](#astro-preview)와 유사하게, 정적 `dist/` 디렉터리를 제공하기 위해 로컬 서버를 시작합니다.

```js
import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await previewServer.stop();
```

### `sync()`

**타입:** `(inlineConfig: AstroInlineConfig) => number`

[`astro sync`](#astro-sync)와 유사하게 모든 Astro 모듈에 대해 TypeScript 타입을 생성합니다.

```js
import { sync } from "astro";

const exitCode = await sync({
  root: "./my-project",
});

process.exit(exitCode)
```

## Astro Studio CLI


### `astro login`

Astro Studio로 인증합니다. 이는 [astro link](#astro-link)를 포함한 모든 데이터베이스 관리 명령을 실행하는 데 필요합니다.

### `astro link`

Studio에서 호스팅하는 데이터베이스에 연결합니다. 데이터베이스 관리를 위해 [Astro DB 명령](/ko/guides/integrations-guide/db/#astro-db-cli-참조)을 실행하는 데 필요합니다. 데이터베이스를 연결하려면 기존 데이터베이스를 선택하거나 새 데이터베이스를 생성하라는 메시지가 표시됩니다.

### `astro logout`

Astro Studio에서 로그아웃하고 로컬에 저장된 인증 키를 제거합니다.